home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / srcuc.zip / SAMPLE.C < prev    next >
C/C++ Source or Header  |  1989-09-20  |  7KB  |  156 lines
  1. /* -*-C-*-
  2.  
  3. Copyright (c) 1987, 1988, 1989 Massachusetts Institute of Technology
  4.  
  5. This material was developed by the Scheme project at the Massachusetts
  6. Institute of Technology, Department of Electrical Engineering and
  7. Computer Science.  Permission to copy this software, to redistribute
  8. it, and to use it for any purpose is granted, subject to the following
  9. restrictions and understandings.
  10.  
  11. 1. Any copy made of this software must include this copyright notice
  12. in full.
  13.  
  14. 2. Users of this software agree to make their best efforts (a) to
  15. return to the MIT Scheme project any improvements or extensions that
  16. they make, so that these may be included in future releases; and (b)
  17. to inform MIT of noteworthy uses of this software.
  18.  
  19. 3. All materials developed as a consequence of the use of this
  20. software shall duly acknowledge such use, in accordance with the usual
  21. standards of acknowledging credit in academic research.
  22.  
  23. 4. MIT has made no warrantee or representation that the operation of
  24. this software will be error-free, and MIT is under no obligation to
  25. provide any services, by way of maintenance, update, or otherwise.
  26.  
  27. 5. In conjunction with products arising from the use of this material,
  28. there shall be no use of the name of the Massachusetts Institute of
  29. Technology nor of any adaptation thereof in any advertising,
  30. promotional, or sales literature without prior written consent from
  31. MIT in each case. */
  32.  
  33. /* $Header: sample.c,v 9.24 89/09/20 23:11:19 GMT cph Exp $ */
  34.  
  35. /* This file is intended to help you find out how to write primitives.
  36.    Many concepts needed to write primitives can be found by looking
  37.    at actual primitives in the system.  Hence this file will often
  38.    ask you to look at other files that contain system primitives.  */
  39.  
  40. /* Files that contain primitives must have the following includes
  41.    near the top of the file.  */
  42. #include "scheme.h"
  43. #include "prims.h"
  44.  
  45. /* Scheme.h supplies useful macros that are used throughout the
  46.    system, and prims.h supplies macros that are used in defining
  47.    primitives.  */
  48.  
  49. /* To make a primitive, you must use the macro DEFINE_PRIMITIVE
  50.    with six arguments, followed by the body of C source code
  51.    that you want the primitive to execute.
  52.    The six arguments are:
  53.    1. A string representing the scheme name that you want to identify
  54.       this primitive with.
  55.    2. The name you want to give to this body of code (a C procedure
  56.       name).  By convention, all such names begin with `Prim_'.
  57.    3. The minimum number of arguments that this scheme primitive
  58.       should receive.  Currently this is not implemented and should be
  59.       the same as the maximum number of arguments (or 0 if the maximum
  60.       is the special symbol LEXPR).
  61.    4. The maximum number of arguments that this scheme primitive
  62.       should receive.  If this primitive will take any number of
  63.       arguments, use LEXPR here.
  64.    5. A documentation string, or 0 meaning no documentation.
  65.  
  66.    The value returned by the body of code following the
  67.    DEFINE_PRIMITIVE is the value of the scheme primitive.  Note that
  68.    this must be a SCHEME_OBJECT (with type tag and datum
  69.    field), and not an arbitrary C object.
  70.  
  71.    As an example, here is a primitive that takes no arguments and
  72.    always returns SHARP_F (SHARP_F is defined in scheme.h and
  73.    identical to the scheme object #F. SHARP_T is identical to the
  74.    scheme object #T).  */
  75.  
  76. DEFINE_PRIMITIVE ("RETURN-SHARP-F", Prim_return_sharp_f, 0, 0, 0)
  77. {
  78.   PRIMITIVE_HEADER (0);
  79.  
  80.   PRIMITIVE_RETURN (SHARP_F);
  81. }
  82.  
  83. /* This will create the primitive RETURN-SHARP-F and when a new Scheme
  84.    is made (with the Makefile properly edited to include this file),
  85.    evaluating (make-primitive-procedure 'return-sharp-f) will return a
  86.    primitive procedure that when called with no arguments, will return
  87.    #F.  */
  88.  
  89. /* Here's another example that shows the use of the `ARG_REF' macro to
  90.    get one of the arguments to the primitive: */
  91.  
  92. DEFINE_PRIMITIVE ("IDENTITY", Prim_identity, 1, 1, 0)
  93. {
  94.   PRIMITIVE_HEADER (1);
  95.  
  96.   PRIMITIVE_RETURN (ARG_REF (1));
  97. }
  98.  
  99. /* Some primitives may have to allocate space on the heap in order
  100.    to return lists or vectors.  There are two things of importance to
  101.    note here.  First, the primitive is responsible for making sure
  102.    that there is enough space on the heap for the new structure that
  103.    is being made.  For instance, in making a PAIR, two words on the
  104.    heap are used, one to point to the CAR, one for CDR.  The macro
  105.    Primitive_GC_If_Needed is supplied to let you check if there is
  106.    room on the heap.  Primitive_GC_If_Needed takes one argument which
  107.    is the amount of space you would like to allocate.  If there is not
  108.    enough space on the heap, a garbage collection happens and
  109.    afterwards the primitive is restarted with the same arguments. The
  110.    second thing to notice is that the primitive is responsible for
  111.    updating Free according to how many words of storage it has used
  112.    up.  Note that the primitive is restarted, not continued, thus any
  113.    side effects must be done after the heap overflow check since
  114.    otherwise they would be done twice.
  115.  
  116.    A pair is object which has a type TC_LIST and points to the first
  117.    element of the pair.  The macro MAKE_POINTER_OBJECT takes a type
  118.    code and an address or data and returns a scheme object with that
  119.    type code and that address or data.  See scheme.h and the files
  120.    included there for the possible type codes.  The following is the
  121.    equivalent of CONS and takes two arguments and returns the pair
  122.    which contains both arguments. For further examples on heap
  123.    allocation, see the primitives in "list.c", "hunk.c" and
  124.    "vector.c".  */
  125.  
  126. DEFINE_PRIMITIVE ("NEW-CONS", Prim_new_cons, 2, 2, 0)
  127. {
  128.   PRIMITIVE_HEADER (2);
  129.   PRIMITIVE_RETURN (cons ((ARG_REF (1)), (ARG_REF (2))));
  130. }
  131.  
  132. /* The following primitive takes three arguments and returns a list
  133.    of them.  Note how the CDR of the first two pairs points
  134.    to the next pair.  Also, scheme objects are of type SCHEME_OBJECT
  135.    (defined in object.h).  Note that the result returned can be
  136.    held in a temporary variable even before the contents of the
  137.    object are stored in heap.  */
  138.  
  139. DEFINE_PRIMITIVE ("WHY-SHOULDNT-THE-NAME-BE-RANDOM?", Prim_utterly_random, 3, 3, 0)
  140. {
  141.   PRIMITIVE_HEADER (3);
  142.   PRIMITIVE_RETURN
  143.     (cons ((ARG_REF (1)),
  144.        (cons ((ARG_REF (2)),
  145.           (cons ((ARG_REF (3)),
  146.              EMPTY_LIST))))));
  147. }
  148.  
  149. /* Here is a primitive that tries to add 3 to its argument.  */
  150.  
  151. DEFINE_PRIMITIVE ("3+", Prim_add_3, 1, 1, 0)
  152. {
  153.   PRIMITIVE_HEADER (1);
  154.   PRIMITIVE_RETURN (long_to_integer ((arg_integer (1)) + 3));
  155. }
  156.